[src/doc/book] Check 03-08-source-replacement.md

[src/doc/book] Update 03-10-policies.md from policies.md

[src/doc/book] Check 03-07-pkgid-spec.md

[src/doc/book] Update 03-02-manifest.md from manifest.md

[src/doc/book] Apply 01-*.md changes into index.md

[src/doc/book] Update guide.md and 02-*.md from guide.md

[src/doc/book] Check faq.md

[src/doc/book] Update 03-09-external-tools.md from external-tools.md

[src/doc/book] Update 03-04-environment-variables.md from environment-variables.md

[src/doc/book] Update 03-06-crates-io.md from crates-io.md

[src/doc/book] Update 03-05-build-scripts.md from build-script.md

[src/doc/book] Update 03-03-config.md from config.md

[src/doc/book] Add .gitignore

Using `mdbook init` command.

Also, update `.gitignore` file manually and add a leading slash.
(Upstream fix for mdBook: <https://github.com/azerupi/mdBook/pull/413>)

[src/doc/book] Import from cargo-book repo

Auto merge of #4451 - steveklabnik:relax-rustdoc-tests, r=alexcrichton

relax rustdoc tests

This was asserting on the output directly, rather than just what it contains.

In https://github.com/rust-lang/rust/pull/44138 we are adding deprecations, and so it
breaks these tests.

Don't use deprecated rustdoc flags in tests

In rust-lang/rust#44138 we are adding deprecations, and so it
breaks these tests.

Auto merge of #4440 - nisargthakkar:publish_target, r=alexcrichton

Adding target support to cargo package and cargo publish

Fixing Issue #4012

Same as #4077 but couldn't reopen the PR due to force push after rebasing from master

Removing redundant extern

Adding tests for --target with cargo publish and cargo package

Adding target support to cargo package and cargo publish

Auto merge of #4442 - Xanewok:process-builder-program, r=alexcrichton

Allow to substitute executed program in `ProcessBuilder`

Extends #4424. Sorry for the noise, turns out it'd also be useful to substite the executed program (e.g. for rls, which needs to use a rustc shim itself) without having to copy over manually all parts of the `ProcessBuilder`.

While I'm at it, do you think this needs even more functionality, like being able to specify `None` for the `cwd` or `jobserver` (currently API exposes only ability to specify `Some(...)` as values for those)?

r? @alexcrichton

Auto merge of #4445 - alexcrichton:bump, r=matklad

Bump Cargo to 0.23.0

Fix tests on nightly

Bump Cargo to 0.23.0

Allow to substitute executed program in `ProcessBuilder`

Auto merge of #4441 - vignesh-sankaran:manifest-doc-fix, r=alexcrichton

Replace maintenance status with ellipses

Since the default maintenance status isn't set to none if it isn't set, feel it'd be more appropriate to have ellipses instead like the other badge docs.

Replace maintenance status badge none with ellipses

Auto merge of #4439 - ishitatsuyuki:bench-cleanup, r=matklad

Gate extern crates for bench tests

I tried my best to skim through the `extern crate` statements, and I hope this will unblock the unused extern crates PR.

Fix remaining test failures

tests/cfg: allow unused extern crates

tests/build-script: allow unused extern crates

Gate feature for bench tests

Gate extern crates for bench tests

Auto merge of #4358 - Mark-Simulacrum:fix-cfg-cargo, r=alexcrichton

Discover crate type information late if necessary.

Some crates aren't found during eager crate-type searching due to being behind `cfg(...)` flags. We still want to be able to handle these, though, so when necessary we now call rustc again to get crate-type information for these cfg-ed crates.

This is necessary for https://github.com/rust-lang/rust/pull/41991.

r? @alexcrichton

Auto merge of #4437 - ishitatsuyuki:deps-purge, r=matklad

Purge deps, round 2

Sorry for creating so much iterations, I have no local build of the new compiler :)

Discover crate type information late if necessary.

Some crates aren't found during eager crate-type searching due to being
behind `cfg(...)` flags. We still want to be able to handle these,
though, so when necessary we now call rustc again to get crate-type
information for these cfg-ed crates.

Purge deps, round 2

Auto merge of #4435 - ishitatsuyuki:deps-purge, r=matklad

Purge unused extern crates

Purge unused extern crates

Auto merge of #4433 - alexcrichton:unstable-features, r=matklad

Add infrastructure for nightly features and flags

This PR starts adding infrastructure in Cargo for nightly features and nightly flags. The current design looks like:

* There's a new `package.cargo-features` manifest key which accepts an array of strings. This array of strings is the list of enabled Cargo features for that crate.
* A new suite of flags behind `-Z`, like the compiler, are accepted on the command line for all commands.
* Features and unstable flags in Cargo are required to be used on Cargo's nightly channel, which is the same as Rust's nightly channel.
* Features and unstable flags cannot be used on the stable/beta channels of Rust/Cargo.
* Crates which enable features in their manifest are disallowed from being published to crates.io

The motivation behind this support is unblock a number of efforts in Cargo by allowing them to safely get implemented behind a nightly feature gate. Once behind a feature gate they can iterate in-tree without having to worry about "insta stability" and we can also get valuable usage feedback about upstream users.

Closes https://github.com/rust-lang/cargo/issues/4409

Add infrastructure for nightly Cargo flags

Add support for nightly features in Cargo

Auto merge of #4431 - vignesh-sankaran:maintenance-badge-docs, r=alexcrichton

Add maintenance badge docs

Pending merging of [this PR for crates.io](https://github.com/rust-lang/crates.io/pull/952). This should close off [#704 on crates.io](https://github.com/rust-lang/crates.io/issues/704). I've also updated the badge metadata docs and reordered the fields into groups by build, code coverage, and maintenance.

So I've decided to put the list of possible badge options in the documentation, we'll have to find another place to put more detailed descriptions of the available maintenance badges.

Added maintenance badge and reordered badge metadata fields

Auto merge of #4432 - potocpav:patch-1, r=matklad

Correct a paragraph

The previous formulation was incorrect in the descriptions of the `x` and `y` version numbers.

Correct an inaccuracy

Auto merge of #4429 - ishitatsuyuki:test-purge, r=matklad

cargotest: purge deps

Blocking rust-lang/rust#42588.

Correct and reword a paragraph

The previous formulation was incorrect in the descriptions of the `x` and `y` version numbers.

cargotest: purge deps

Auto merge of #4424 - Xanewok:process-builder-api, r=alexcrichton

Add `fn args_replace` and `fn get_program` to `ProcessBuilder`

`Executor::exec()` provides a `ProcessBuilder` argument representing compiler call and if someone wants to use it or modify it for their own purposes, they have to (partially) recreate it themselves.

This:
* makes the argument modification possible (via `args_replace`, analogous to `env_remove`)
* exposes the program that will be run (via `get_program`, in case `rustc` is overriden via wrapper etc.).

r? @alexcrichton

Add `fn args_replace` and `fn get_program` to `ProcessBuilder`

Auto merge of #4416 - Xanewok:more-executor-params, r=alexcrichton

Expose `Target` and `Unit` params to appropriate `Executor` callbacks

This effectively does only two things:
* Pass existing `&Unit` to `init()`
* Pass existing `&Target` to `exec()`s

Also updated doc comments slightly.

The `init()` is called for every `Work` preparation by `rustc()` and since it's not called once (not sure if intended?), it'd be good to include more information for which `Unit` the `rustc` process invocation has been initially prepared (I think more importantly it shows that `init()` is called many times for many targets).
Additionally, it'd be good to know about `Unit` compiled in the `exec()` callbacks in more structured manner (so the user doesn't have to parse the `ProcessBuilder` arguments and/or make certain assumptions) and since `target` was already cloned and moved into the closure, it was only a matter of exposing it.

I think it'd be ideal to provide all the necessary information to recreate a `Unit` but with a static lifetime needed for the closure, however this would mean cloning more data per-target ([`Kind`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_rustc/mod.rs#L41) should be basically free, however not sure if cloning [`Profile`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs#L151) is acceptable). With this, `Executor` users could query `Context` more easily (e.g. to get a unit dep graph! :smile:), as the API accepts `Unit`s in many places.

r? @alexcrichton
cc @nrc

EDIT:
This changes the public API, not sure if there's something else I should do about it, only ran `cargo test` locally.

Auto merge of #4364 - RalfJung:feat, r=alexcrichton

Required dependencies are not features

Also, while I was at it, I fixed an error message which complained about something not being an optional dependency, when really what mattered was that it was not a dependency at all.

I made a bunch of guesses about how things work. These guesses ended up as comments in the commit (so hopefully, the next reader of these files has to guess less). I am not totally certain these comments are all correct, so please yell if not. :)

In particular, for resolve_features, I observed that dependencies get compiled even when they are not returned from that function. But judging from how the function used to behave, it actually returns all dependencies, even those that have nothing to do with any features. (Making the name rather misleading, TBH...)

Fixes #4363

Expose `Target` and `Unit` params to appropriate `Executor` callbacks

fix borrowing the shell twice

Using required dep as a feature is a warning for now, not an error

Auto merge of #4400 - behnam:pr4157, r=alexcrichton

[check|build|rustc] Add --all-targets option

`cargo check` does not check all targets by default, and to check all,
you need to call it `cargo check --tests --examples --bins --benches`.

Here, we implement `--all-targets` For `check`, `build`, and `rustc`.

For consitency, `--all-targets` is also added to other commands like
`test` although "all targets" is the default behavior.

This is a rebase of <https://github.com/rust-lang/cargo/pull/4157>

improve misleading error message

detect required dependencies used as features

test for mandatory dependencies not to be considered features

Auto merge of #4404 - parkovski:master, r=alexcrichton

Fix #4370 - init panic in C:\ or /

This fixes the crash in this issue, but the error message is strange - unable to create directory 'C:\\.'. I don't have write permissions there without becoming admin, so I suspect it's just a permission issue, but the weird error can be fixed by calling Path::canonicalize on line 300.

Fix #4370 - init panic in C:\ or /

Auto merge of #4402 - bluss:doc-rustdocflags, r=alexcrichton

Document `RUSTDOCFLAGS`

Documentation for this environment variable was missing. It's supported in stable releases of Rust already.

Document `RUSTDOCFLAGS`

Auto merge of #4389 - matklad:testless, r=alexcrichton

Allow to skip test code during publishing

closes #4365

I don't have time to review this code carefully right now, but looks like it does the job.

Allow to skip test code during publishing

Auto merge of #4393 - burtonageo:update-cargo-new-template, r=matklad

Update lib template for `cargo new` so that the placeholder test contains an assertion

When you run `rustfmt` on the default generated lib template, it modifies it as shown [here](https://play.rust-lang.org/?gist=bd44610731e26e76719e75d47e598990&version=undefined)

[check|build|rustc] Add --all-targets option

`cargo check` does not check all targets by default, and to check all,
you need to call it `cargo check --tests --examples --bins --benches`.

Here, we implement `--all-targets` For `check`, `build`, and `rustc`.

For consitency, `--all-targets` is also added to other commands like
`test` although "all targets" is the default behavior.

This is a rebase of <https://github.com/rust-lang/cargo/pull/4157>

Auto merge of #4398 - debris:url_4394, r=alexcrichton

Fixed panic when canonicalizing not-a-base-url, fixes #4394

Fixes #4394. Majority of the changes are caused by propagating error upstream to `SourceId` and `GitSource`.

Fix implementation and tests for cannot-be-a-base-url canonicalization

Fixed panic when canonicalizing not-a-base-url, fixes #4394

Auto merge of #4396 - vignesh-sankaran:documentation-blacklist-list-fix, r=matklad

Fix list rendering in manifest.md

Fixes a list rendering problem introduced in #4237.

Fix list rendering for blacklisted hosts

Add a placeholder assertion in the new lib project template

Fix tests

Update lib template for `cargo new` so that it conforms to rustfmt style by default

Auto merge of #4390 - alexcrichton:read-hard-links, r=matklad

Use `same-file` to avoid unnecessary hard links

This is targeted at removing the need for a workaround in rust-lang/rust#39518,
allowing the main rust build system to move back to hard links which should be
much more efficient.

Auto merge of #4386 - pornel:backups, r=alexcrichton

Exclude target directory from Time Machine

Fixes #3884

Exclude target directory from Time Machine

Temporary/derived files outside dedicated system directories should be explicitly excluded from backups to prevent undesirable bloat and churn.

Use `same-file` to avoid unnecessary hard links

This is targeted at removing the need for a workaround in rust-lang/rust#39518,
allowing the main rust build system to move back to hard links which should be
much more efficient.

Auto merge of #4384 - ivanbakel:unused_mut, r=alexcrichton

Fixed some variables being unnecessarily mutable

### Changes

Some variables are marked `mut` when they don't need to be. This PR changes those variables to no longer be `mut`.

### Context

PR on https://github.com/rust-lang/rust/pull/43582

tl:dr; There's a bug with the mutability checker that sometimes marks mutable ref variables as being used when they're not.

Auto merge of #4382 - Xanewok:expose-filter-rule, r=alexcrichton

Expose ops::cargo_compile::FilterRule

I've been mindlessly copying and consuming the Cargo API to work on the build plan prototype for RLS and I noticed that, it seems, pub `ops::cargo_compile::CompileFilter` is exported, but not the `ops::cargo_compile::FilterRule`, which `CompileFilter` uses, as a part of a public API.

If I'm wrong and missing something, feel free to ignore/close it. It was possible to match/destructure `CompileFilter` before, but with this change it's possible to use the underlying type.

Fixed instance in Windows cfg.

Fixed variables being unnecessarily mut.

Auto merge of #4378 - behnam:ignore, r=alexcrichton

[sources/path] Support leading slash in glob patterns

Background: https://github.com/rust-lang/cargo/issues/4268

This diff takes us to **Stage 1.1** of the migration plan by allowing
glob patterns to include a leading slash, so that glob patterns can be
updated, if needed, to start with a slash, closer to the future behavior
with gitignore-like matching.

Why is this stage needed?

It's common to have `package.include` set like this:
```
include = ["src/**"]
```
In old interpretation, this would only include all files under the `src`
directory under the package root. With the new interpretation, this
would match any path with some directory called `src`, even if it's not
directly under the package root.

After this patch, package owners can start marking glob patters with a
leading slash to fix the warning thrown, if any.

One thing to notice here is that there are no extra matchings, but, if
a manifest has already a pattern with a leading slash, this would
silently start matching it with the paths. I believe this is fine, since
the old behavior would have been for the pattern to not match anything,
therefore the item was useless.

See also <https://github.com/rust-lang/cargo/issues/4377> for suggestion
to throw warning on useless/invalid patterns in these fields.

Auto merge of #3611 - tylerwhall:stable-metadata, r=alexcrichton

Stable metadata hashes across workspaces

Currently a crate from a path source will have its metadata hash incorporate its absolute path on the system where it is built. This always impacts top-level crates, which means that compiling the same source with the same dependencies and compiler version will generate libraries with symbol names that vary depending on where the workspace resides on the machine.

This is hopefully a general solution to the hack we've used in meta-rust to make dynamic linking reliable.
meta-rust/meta-rust@0e6cf94

For paths inside the Cargo workspace, hash their SourceId relative to the root of the workspace. Paths outside of a workspace are still hashed as absolute.

This stability is important for reproducible builds as part of a larger build system that employs caching of artifacts, such as OpenEmbedded.

OpenEmbedded tightly controls all inputs to a build and its caching assumes that an equivalent artifact will always result from the same set of inputs. The workspace path is not considered to be an influential input, however.

For example, if Cargo is used to compile libstd shared objects which downstream crates link to dynamically, it must be possible to rebuild libstd given the same inputs and produce a library that is at least link-compatible with the original. If the build system happens to cache the downstream crates but needs to rebuild libstd and the user happens to be building in a different workspace path, currently Cargo will generate a library incompatible with the original and the downstream executables will fail at runtime on the target.

Expose ops::cargo_compile::FilterRule

Auto merge of #4376 - behnam:virtual, r=alexcrichton

[docs/manifest] Add Virtual Manifest section

Current documentation does not mention Virtual Manifests at all, which
can be confusing because they appear in error messages.

Here we add the definition, and provide a hint about `--all` option for
most cargo commands, which allow the command to work in the way most
probably expected.

Fixes <https://github.com/rust-lang/cargo/issues/3526>

Auto merge of #4374 - behnam:new-init, r=alexcrichton

[cargo_new] Hint to use `cargo init` on existing dir

The `new` command always expects a non-existing path. The `init` command
always expects an existing path. Therefore, it makes sense to hint to
use `init` if the pre-condition to `new` is not satisfied.

Fixes <#4366>

Auto merge of #4375 - behnam:root-vs-repo, r=alexcrichton

[docs] Update language regarding repository vs package root

In the current documentation, there are many places with language that
assumes a *repository* (as in VCS) is the same as *package root* (the
directory where `Cargo.toml` sits).

With the new workspace features, this is far from true now, and the
inaccurate language makes it difficault for newbies or developers
without much familiarity with the cargo internals with authoring their
manifest files.

This diff tries to use the right terms for places any of these concepts
is referred to:

* Package root,
* Workspace root,
* VCS repository, and
* Package repository/index, like crates.io.

Fixes <https://github.com/rust-lang/cargo/issues/4367>

[sources/path] Support leading slash in glob patterns

Background: https://github.com/rust-lang/cargo/issues/4268

This diff takes us to **Stage 1.1** of the migration plan by allowing
glob patterns to include a leading slash, so that glob patterns can be
updated, if needed, to start with a slash, closer to the future behavior
with gitignore-like matching.

Why is this stage needed?

It's common to have `package.include` set like this:
```
include = ["src/**"]
```
In old interpretation, this would only include all files under the `src`
directory under the package root. With the new interpretation, this
would match any path with some directory called `src`, even if it's not
directly under the package root.

After this patch, package owners can start marking glob patters with a
leading slash to fix the warning thrown, if any.

One thing to notice here is that there are no extra matchings, but, if
a manifest has already a pattern with a leading slash, this would
silently start matching it with the paths. I believe this is fine, since
the old behavior would have been for the pattern to not match anything,
therefore the item was useless.

See also <https://github.com/rust-lang/cargo/issues/4377> for suggestion
to throw warning on useless/invalid patterns in these fields.

[docs/manifest] Add Virtual Manifest section

Current documentation does not mention Virtual Manifests at all, which
can be confusing because they appear in error messages.

Here we add the definition, and provide a hint about `--all` option for
most cargo commands, which allow the command to work in the way most
probably expected.

Fixes <https://github.com/rust-lang/cargo/issues/3526>

[docs] Wrap long lines

[docs] Update language regarding repository vs package root

In the current documentation, there are many places with language that
assumes a *repository* (as in VCS) is the same as *package root* (the
directory where `Cargo.toml` sits).

With the new workspace features, this is far from true now, and the
inaccurate language makes it difficault for newbies or developers
without much familiarity with the cargo internals with authoring their
manifest files.

This diff tries to use the right terms for places any of these concepts
is referred to:

* Package root,
* Workspace root,
* VCS repository, and
* Package repository/index, like crates.io.

[cargo_new] Hint to use `cargo init` on existing dir

The `new` command always expects a non-existing path. The `init` command
always expects an existing path. Therefore, it makes sense to hint to
use `init` if the pre-condition to `new` is not satisfied.

Fixes <https://github.com/rust-lang/cargo/issues/4366>

[bin/init] Update USAGE

Auto merge of #4372 - frankmcsherry:patch-1, r=alexcrichton

Modernize explanation of `build.rs`

After some recent head-banging, it was explained to me that `"build.rs"` is a special file name, and that Cargo will build such a file even if you do not expect it to, for example if `Cargo.toml` contains the commented out line

```
#build = "build.rs"
```

Some experimentation lead me to the described behavior, but if it misses any subtle details please feel free to correct. The old text is incorrect, though.

Auto merge of #4369 - Wallacoloo:specifying-dependencies-typo, r=alexcrichton

Fix repeated "to to" in Specifying Dependencies

Fixes the typo:

> [...] boil down to the ability to **to** work with a crate [...]

Modernize explanation of `build.rs`

After some recent head-banging, it was explained to me that `"build.rs"` is a special file name, and that Cargo will build such a file even if you do not expect it to, for example if `Cargo.toml` contains the commented out line

```
#build = "build.rs"
```

Some experimentation lead me to the described behavior, but if it misses any subtle details please feel free to correct. The old text is incorrect, though.

Fix repeated "to to" in Specifying Dependencies